Skip to content

Conversation

@kyleconroy
Copy link
Collaborator

This Go tool regenerates explain.txt files by splitting each query.sql
into individual statements and running EXPLAIN AST via clickhouse local.

For tests with multiple statements:

  • First statement → explain.txt
  • Subsequent statements → explain_N.txt (N = 2, 3, ...)

Usage:
./regenerate-explain -test # Process single test
./regenerate-explain # Process all tests
./regenerate-explain -dry-run # Preview statements

This Go tool regenerates explain.txt files by splitting each query.sql
into individual statements and running EXPLAIN AST via clickhouse local.

For tests with multiple statements:
- First statement → explain.txt
- Subsequent statements → explain_N.txt (N = 2, 3, ...)

Usage:
  ./regenerate-explain -test <name>   # Process single test
  ./regenerate-explain                # Process all tests
  ./regenerate-explain -dry-run       # Preview statements
- Split query.sql into individual statements
- Create subtest for each statement (stmt1, stmt2, etc.)
- Check explain.txt for first statement, explain_N.txt for Nth statement
- Skip statements beyond first if no explain file exists (not yet regenerated)
- Skip tests with all statements commented out
- Add explain files for 00002_system_numbers (13 statements)

This allows tests with multiple SQL statements to verify each one
against its corresponding explain output.
@kyleconroy kyleconroy force-pushed the claude/regenerate-explain-txt-7kuaq branch from cb24f4b to d149200 Compare December 28, 2025 07:17
Update the regenerate-explain tool to only generate explain_N.txt
files for statements 2+, preserving the existing explain.txt files
for the first statement. This prevents version-specific differences
in ClickHouse EXPLAIN AST output from modifying the golden files.
Generate EXPLAIN AST output for statements 2+ in query.sql files
that contain multiple SQL statements. This enables the parser test
to test each statement as a subtest.

- 99,169 new explain_N.txt files generated
- Existing explain.txt files preserved unchanged
- Some statements skipped due to intentionally invalid SQL
Add nil checks to explainCreateQuery and explainRenameQuery to handle
cases where the parser returns nil AST nodes wrapped in interfaces.
Add support for explain_todo in metadata.json to skip individual
statement subtests. This allows marking specific statements as
pending without skipping the entire test case.

Usage in metadata.json:
  {"explain_todo": {"stmt2": true, "stmt5": true}}

This skips stmt2 and stmt5 subtests while running all other statements.
- Remove Todo field from testMetadata struct in parser_test.go
- Remove -check-skipped flag and related logic
- Remove todo key from 146 metadata.json files
- Update cmd/next-test to only support -format flag
- Update CLAUDE.md documentation

The explain_todo key now provides more granular control for
skipping specific statement tests within a test case.
Add a new -check-explain flag that runs tests marked in explain_todo
to see if they now pass. Similar to -check-format but for explain tests.

Usage:
  go test ./parser/... -check-explain -v 2>&1 | grep "EXPLAIN PASSES NOW"

When a test passes, it automatically removes the statement from
explain_todo in metadata.json.
Add explain_todo metadata entries for all currently failing stmt tests.
This allows the test suite to pass while marking tests that need
parser/explain implementation work.

Updated 2700+ metadata.json files with statement-specific explain_todo entries.
Add a new -explain flag that finds tests with explain_todo entries,
sorted by fewest pending statements first. This helps prioritize
tests that are closest to being fully implemented.

Usage:
  go run ./cmd/next-test -explain
@kyleconroy kyleconroy merged commit 8fffa8c into main Dec 28, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants